Will close #3657

Description

This PR enables the same syntax from alt.when to be used in alt.TopLevelMixin.transform_filter.

Honestly, I'm still a bit shocked by how little needed changing in the implementation.
Besides tweaking the signature and handling the deprecated argument, it really was just these 2 lines:

To explain this, _parse_when returns our version of VL-Condition.
We can either use that as-is or unwrap the "test" key, which stores an already parsed test VL-Predicate.

Besides this small change, most of the PR consists of new docs & tests.

Doc (Examples)

Setting up a common chart:

source = data.population.url
chart = (
    alt.Chart(source)
    .mark_line()
    .encode(
        x="age:O",
        y="sum(people):Q",
        color=alt.Color("year:O").legend(symbolType="square"),
    )
)
chart

Singular predicates can be expressed via datum:

chart.transform_filter(datum.year <= 1980)

We can also use selection parameters directly:

selection = alt.selection_point(encodings=["color"], bind="legend")
chart.transform_filter(selection).add_params(selection)

Or a field predicate:

between_1950_60 = alt.FieldRangePredicate(field="year", range=[1950, 1960])
chart.transform_filter(between_1950_60) | chart.transform_filter(~between_1950_60)

Predicates can be composed together using logical operands:

chart.transform_filter(between_1950_60 | (datum.year == 1850))

Predicates passed as positional arguments will be reduced with &:

chart.transform_filter(datum.year > 1980, datum.age != 90)

Using keyword-argument constraints can simplify compositions like:

verbose_composition = chart.transform_filter((datum.year == 2000) & (datum.sex == 1))
chart.transform_filter(year=2000, sex=1)

Tasks

• Deprecate using filter as a keyword argument
  • plan
  • related PR
  • commit
• Replace current .transform_filter() implementation
• Review current tests/failures
  • Was expecting this to be more complicated
  • No test failures
  • One typing issue
• Add new tests for (*predicates, **constraints) syntax (b497039)
• Address predicate dict typing issue
  • Found in (fc672bc)
  • thread
• Update .transform_filter() docstring (7a0cc42)